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Abstract 

QuteCsound is a front-end application for Csound 
written using the Qt toolkit. It has been developed 
since 2008 , and is now part of the Csound distri¬ 
bution for Windows and OS X. It is a code editor 
for Csound, and provides many features for real-time 
control of the Csound engine, through graphical con¬ 
trol interfaces and live score processing. 
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1 Introduction 

QuteCsound was born out of the desire to have a 
cross-platform front-end for Csound [Boulanger, 
2000] like MacCsound [Ingalls, 2005] which only 
runs on OS X. It is based on the idea of hav¬ 
ing real-time control of Csound through graph¬ 
ical widgets, and making Csound accessible for 
novice users. It is however designed to be also 
a powerful editor for advanced users and also 
offline (non-realtime) work. The most recent 
version is 0.5.0. It has been tested on Linux, 
Mac OS X, Windows and Solaris. QuteCsound 
has been translated to Spanish, French, Italian, 
German and Portuguese. 

One of the main goals was also to make a 
new interface for Csound which would be com¬ 
fortable for a musician whose background is not 
in programming. Existing cross-platform inter¬ 
faces for Csound were either too basic or some¬ 
what impractical. The Csound Manual [Cabr¬ 
era, 2010] is very comprehensive, but few front- 
ends take full advantage of its resources like op¬ 
code listing in XML format. 

QuteCsound uses the Csound API [ffitch, 
2005], which enables tight integration and con¬ 
trol of Csound. 

It is licensed under the GPLv3 and LGPLv2 
for compatibility with the Csound licence to 
ease distribution alongside Csound. More in¬ 
formation on QuteCsound can be found in the 


o y «j & % ci c » s H a|| r b R « d ja Et ^ t jp c n jb* J t c ® >. 



Figure 1: The main QuteCsound window 
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Figure 2: The transport bar 


QuteCsound Front page 1 and the QuteCsound 
sources and binaries can be found on its Source- 
forge page 2 . 

2 GUI 

The main application window is shown in figure 
1. The main component is a text editor with 
syntax highlighting. Documents can be opened 
as separate tabs in this area. There is a large 
icon bar with the main actions, which contains 
the usual open/save and cut/copy/paste action 
icons, a section with transport controls (see fig¬ 
ure 2), and a section for handling visibility of 
the rest of the application windows and panels. 

Around the editor many dockable widgets can 
be positioned freely. These dockable widgets 
are: 

Widget Panel In the widget panel, control 
widgets like sliders and knobs can be cre¬ 
ated. The design and manipulation of the 

1 htt p: / / qut ecsound. sour ceforge. net 

2 http: / / www. sourceforge. net / pro j ect s / qut ecsound 





























widgets is all graphical, and requires no 
textual programming. See 2.1 below. 

Manual Panel The html version of the 
Csound Manual can be displayed in this 
panel. The reference for an opcode under 
the editor cursor can be called with the de¬ 
fault short-cut Shift+Fl. 

Console Panel The output from Csound for 
the current document is displayed in this 
panel. 

Inspector Panel Shows a dynamically gener¬ 
ated hierarchical list of important sections 
from the current file. It shows instrument 
definitions and labels, definition of User de¬ 
fined opcodes, f-table definitions, and score 
sections. 

When the current document tab is changed, 
all the panels which depend on the document 
like the widget panel and the inspector panel, 
change to show the current data. 

There are three additional windows in the 
GUI: 

Configuration dialog Allows setting options 
for Csound execution, Environment and in¬ 
terface options. 

Utilities dialog Simplifies usage of the 
Csound utilities -applications which pre- 
process files for certain opcodes- can be 
called and controlled through this dialog 
window. 

Live Event Panels These windows which 
vary in number according to the current 
document contain a spreadsheet-like in¬ 
terface for manipulating Csound score 
events which can be sent, manipulated and 
looped while Csound is running. They can 
also be processed using the simple python 
qutesheet API (see section 2.3). 



Figure 3: Widget Panel detail 

An example of how the widget panel can be 

used is shown in figure 3. 

These are the available data widgets: 

Slider Ordinary sliders which become horizon¬ 
tal or vertical depending on the relation be¬ 
tween width and height. 

Knob Simple rotary knobs. 

Labels and Displays Text widgets that dis¬ 
play immutable text (labels), or text that 
can be changed only from Csound, not us¬ 
ing the mouse 4 . 

Text Editor A text entry widget. 

Number widgets The ScrollNumber and 
SpinBox widgets offer number value inputs 
and outputs with mouse and keyboard 
control. 

Menus The menu widget allows creating a 
Drop-down or Combo Box for selection 
from a list. 

Controller The controller widget can be a 
slider, a meter or an XY controller. It can 
also be used as a “LED” display. 


2.1 Widgets 

The widget panel allows creation of versatile 
graphical control interfaces. Data widgets pro¬ 
vide bi-directional interchange of values with 
Csound through the API. The values can be 
updated synchronously or asynchronously de¬ 
pending on the QuteCsound configuration and 
the usage of invalue/outvalue or chnget/chnset 3 
opcodes in the csd file. 

3 The invalue/outvalue opcodes call a registered call¬ 
back when they are used, while chnget/chnset only 
change internal values which must be polled 


Button Buttons can be data widgets (sending 
different values depending on whether they 
are pressed or not) or score event genera¬ 
tors. They can also hold images. 

CheckBox A simple checkbox which can take 
a value of 1 or 0. 

There are three other widgets which are used to 
display information from Csound: 

4 While this separation is not really necessary or use¬ 
ful, it follows the MacCsound format choices, and was 
kept for compatibility purposes only 








































Figure 4: The Widget Preferences dialog 

Graphs The Graph Widget displays Csound 
F-tables, as they are created by Csound, 
and also displays data from the dispfft and 
display opcodes, which allow monitoring 
any signal or its spectrum. There is a Com- 
boBox which allows selection of the current 
tables. The table shown can also be se¬ 
lected through a Csound API channel. 

Scopes The Scope widget shows visual repre¬ 
sentations of Csound output buffer. It can 
act as a traditional Oscilloscope or as a Lis- 
sajou, or Poincare display. 

Consoles The Console widget shows the 
Csound console output as a widget in the 
widget panel. 

Widgets can be created by right-clicking on 
the widget panel, and selecting a type of widget 
from a list. They can be moved and resized 
by entering the ‘Edit Mode’ with the keyboard 
short-cut Ctrl+E. 

All widgets have a configuration dialog which 
can be shown by right clicking on them and se¬ 
lecting ‘Properties’ or by double clicking when 
in edit mode. The Properties dialog for a text 
widget is shown on figure 4. Properties like size 
and position can be set in these dialogs. The 
channel name through which the widget trans¬ 
mits (if it can according to its type) can also be 
set here. 

To receive data from the widgets, they must 
be assigned to a control variable ( k-rate ) using 
the invalue opcode like this: 

kval invalue "channel" 

Conversely, to send data to a widget, the out¬ 
value opcode can be used. 

outvalue "chan", kval 


There are some handy organization functions 
for selected widgets like align and distribute to 
aid in creating better looking widget panels. 

The widgets are saved as text in the csd file, 
but this text is always hidden from the user 5 . 
Each widget is currently represented by a single 
line of text, which looks something like this: 

ioSlider {23, 244} {414, 32} -1.000000 
1.000000 -1.000000 amount 

This follows the original MacCsound format 
strictly, which enables QuteCsound to open and 
generate files which are interchangeable with 
MacCsound. It is somewhat human-readable 
and editable, but impossible to extend without 
breaking compatibility. A lot of internal work 
has already been done to move past the MacC¬ 
sound widget format to an XML based format 
which will allow easier extensibility and parsing, 
and new widget types. 

2.2 Live events panel 

Each document can have any number of Live 
Event Panels. A live event panel is a place 
where Csound score events can be placed for 
interactive usage during a Csound run. It is 
shown in figure 5. The live event panel can dis¬ 
play the information in the traditional Csound 
score format or as a spreadsheet with editable 
cells. It offers a group of common processing 
functions which can be applied quickly to a 
group of cells like addition, multiplication, and 
generation functions like fill linearly or exponen¬ 
tially or random number generation. There is 
also support for some of the basic Csound Score 
preprocessor features like tempo control and the 
carry operator 

Score events can be copied/pasted to/from 
text view and sheet view seamlessly. 

Live Event Panels are also stored as text in 
the main csd file, and are hidden from the user 
in the main text editor. 

2.3 The QuteSheet Python API 

A simple python API has been devised to enable 
transformation of data from the Live Events 
Panel using Python. The cells (both the se¬ 
lected and the complete set) are passed to the 
python script as arrays in any particular orga¬ 
nization (by rows, by columns, by individual 
cells), and can be returned with a single func¬ 
tion specifying the new data and where it should 

5 This behavior will probably change in the future to 
allow text modification of the widgets 





















Figure 5: The Live Events Panel 


be placed in the sheet. The python scripts can 
be stored in a directory which is scanned every 
time the right-click menu in the event sheet is 
triggered, effectively allowing “live coding” of 
score transformations while the Csound audio 
engine is running. 



2.4 Code Graph 

QuteCsound can parse the currently active doc¬ 
ument to generate a dot language file, which can 
be rendered using graphviz 6 . Although compli¬ 
cated files produce diagrams that are too com¬ 
plex, this feature is useful for beginners to see 
how the variables and opcodes are connected in 
a visual way. The output of this action can be 
seen in figure 6. 

3 Architecture 

QuteCsound requires Qt 4[Nokia, 2010], 
Csound and libsndfile[de Castro Lopo, 2010] to 
build. 

Qt is a mature cross-platform graphical tool¬ 
kit, which is used in several well known free- 
software audio projects like QJackCtl. It also 
has cross-platform libraries for non GUI stuff 
like networking, XML parsing, printing and 
threading which has saved time and avoided the 
need for additional dependencies. It also has 
extensive facilities for internationalization and 
translation. It is distributed in separate dy¬ 
namic libraries which can be distributed with 
the executable. 

Libsndfile is a well established audiofile 

6 Graphviz is a package for generating flowchart style 
graphics using the dot language. More information can 
be found on www.graphviz.org 


Figure 6: The Code Graph Output 

read/write library, which is very well main¬ 
tained, stable and efficient. 

All audio and MIDI I/O is handled by Csound 
itself, except the Record function, which copies 
the Csound output buffer after every control 
block to a ring buffer and writes it to disk from 
another thread. This means that QuteCsound 
supports output to Jack, Coreaudio and Win- 
MME as well as generic interfaces like Portau- 
dio. 

Csound can be run either as a com¬ 
pletely independent process in a separate 
Terminal application, on the same appli¬ 
cation thread (usually undesirable) or on 
a separate thread using the API through 
the CsoundPerformanceThread 7 C++ interface 
from interfaces/csPerfThread.hpp in the 
Csound sources. 

Data update is requested by Csound syn¬ 
chronously through its callback functions (set 
using the csoundSetlnputValueCallback and 
csoundSetOutputValueCallback functions) 
when the invalue/outvalue opcodes are used. 
Data for Csound is polled in that callback, but 
data for the widgets is queued, to be processed 

7 this class handles some of the threading issues as¬ 
sociated with passing events to Csound and with start¬ 
ing/pausing/stopping the engine 




















































































































at a slower rate. The values can also be up¬ 
dated asynchronously with the chnset/chnget 
opcodes. The values are then updated from a 
timer triggered thread in QuteCsound, forcing 
locking of values. 

An interesting feature of MacCsound which 
has been emulated in QuteCsound is that wid¬ 
gets with the same channel name update each 
other even when Csound is not running. This is 
useful to avoid Csound code for common things 
like showing the numeric value of a slider wid¬ 
get, and it also gives a (false but expected and 
rewarding) sense of an “always running” en¬ 
gine. In practical terms, this implies that when 
Csound is running, widgets must first take val¬ 
ues generated from Csound, and then propagate 
their values to other widgets. 

3.1 Documentation integration 

The Csound documentation is highly integrated 
in QuteCsound. It can be easily called from 
the Help menu, or to find the reference for the 
opcode under the editor cursor. The documen¬ 
tation also contains an XML file of all the op¬ 
code definitions organized by category. This file 
is used for syntax highlight, but also for show¬ 
ing opcode syntax in the status bar, populating 
an opcode selector organized by categories and 
building the code graph code (to know the in¬ 
put/output variable names and types). 

4 Examples Menu 

The Examples menu in QuteCsound includes 
a large set of introductory examples and tu¬ 
torials, reference examples for the widgets and 
a group of ‘classic’ Csound compositions like 
Boulanger’s Trapped in Convert , and Csound 
realizations of important historical pieces like 
Chowning’s Stria and Stockhausen’s Studie II. 
The examples menu also contains a set of re¬ 
altime synths, some useful files for things like 
I/O monitoring and file processing, and a ‘Fa¬ 
vorites’ menu which shows the csd files from a 
user specified directory. 

5 The future 

Plans for the future include completion of the 
new widget format, and development of new 
widgets like a table widget. It would be nice 
to have a synchronization option to make loops 
sync to a master loop. 

A lot of work has been done to enable the 
exporting of stand alone applications, so this 
will hopefully be finished soon. 


And of course fix some of the bugs along the 
way. 
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